Alternar criativos de anúncios com a API Select URL

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Use a API Select URL para aproveitar o Shared Storage e determinar qual criativo o usuário vai ver nos sites.

Um anunciante ou produtor de conteúdo pode querer aplicar diferentes estratégias de rotação de conteúdo a uma campanha e fazer a rotação dos conteúdos ou criativos para aumentar a eficácia. A API Select URL pode ser usada para executar diferentes estratégias de rotação, como rotação sequencial e rotação distribuída uniformemente, em diferentes sites.

Com a rotação de criativos da API Select URL, é possível armazenar dados, como ID do criativo, contagens de visualizações e interação do usuário, para determinar quais criativos os usuários veem em diferentes sites.

Para mais informações sobre a API subjacente e como a seleção funciona, confira a documentação da API Select URL.

Testar a rotação de criativos

Para testar a rotação de criativos, verifique se a API Select URL e o Armazenamento compartilhado estão ativados:

• Em chrome://settings/content/siteData, selecione Allow sites to save data on your device ou Delete data sites have saved to your device when you close all windows.
• Em chrome://settings/adPrivacy/sites, selecione Site-suggested ads.

Teste nossa demonstração ao vivo do Shared Storage para conferir uma versão em tempo real dos exemplos de código neste documento.

Demonstração com exemplos de código

Neste exemplo:

• creative-rotation.js é o script de terceiros que define o conteúdo a ser girado, junto com os dados que determinam o próximo conteúdo a ser selecionado e exibido, como os pesos neste exemplo. A página do editor executa esse script. Esse script chama o worklet de armazenamento compartilhado para determinar qual conteúdo será exibido com base nos dados disponíveis no armazenamento e na lista de URLs para seleção.

• creative-rotation-worklet.js é o worklet de armazenamento compartilhado de terceiros que procura a estratégia de rotação, calcula o conteúdo a ser publicado em seguida e o retorna.

Como a demonstração funciona

1. Quando um usuário visita a página do editor, ela carrega o script creative-rotation.js de terceiros. O script de rotação de criativos é responsável por carregar e executar o worklet de armazenamento compartilhado. O script fornece à chamada de worklet uma lista de URLs para seleção.
2. No worklet, se o armazenamento compartilhado ainda não tiver sido inicializado, ele será inicializado com a estratégia de rotação e o índice do criativo inicial. A estratégia de rotação inicial usada nesta demonstração é sequencial.
3. O worklet lê o modo de rotação do armazenamento compartilhado e retorna o índice do próximo anúncio. No caso do modo de rotação sequencial, ele também atualiza o índice do criativo no armazenamento compartilhado com o novo valor a ser usado na próxima chamada.O worklet retorna um objeto URN opaco ou FencedFrameConfig com base no valor resolveToConfig usado ao chamar selectURL.
4. O script de rotação de criativos mostra o anúncio selecionado em um frame limitado ou um iframe. Consulte o documento de renderização de um anúncio para saber mais sobre os tipos de retorno.
5. Quando um usuário muda o modo de rotação, o worklet de armazenamento compartilhado atualiza o valor do modo de rotação do criativo armazenado no armazenamento compartilhado.
6. Ao recarregar a página do editor, as etapas 1 a 4 são repetidas, permitindo que a seleção do próximo anúncio seja visualizada com base na estratégia de rotação selecionada.

Amostras de código

Confira abaixo os exemplos de código para creative-rotation.js e creative-rotation-worklet.js.

creative-rotation.js

const contentProducerUrl = 'https://your-server.example';

// Ad config with the URL of the ad, a probability weight for rotation, and the clickthrough rate.
const DEMO_AD_CONFIG = [
  {
    url: `${contentProducerUrl}/ads/ad-1.html`,
    weight: 0.7,
  },
  {
    url: `${contentProducerUrl}/ads/ad-2.html`,
    weight: 0.2,
  },
  {
    url: `${contentProducerUrl}/ads/ad-3.html`,
    weight: 0.1,
  },
];

async function setRotationMode(rotationMode) {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  await creativeRotationWorklet.run('set-rotation-mode', {
    data: { rotationMode }
  });
  console.log(`creative rotation mode set to ${rotationMode}`);
}

async function injectAd() {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  const urls = DEMO_AD_CONFIG.map(({ url }) => ({ url }));

  // Resolve the selectURL call to a fenced frame config only when it exists on the page
  const resolveToConfig = typeof window.FencedFrameConfig !== 'undefined';

  // Run the URL selection operation to determine the next ad that should be rendered
  const selectedUrl = await creativeRotationWorklet.selectURL('creative-rotation', urls, {
    data: DEMO_AD_CONFIG,
    resolveToConfig
  });

  const adSlot = document.getElementById('ad-slot');

  if (resolveToConfig && selectedUrl instanceof FencedFrameConfig) {
    adSlot.config = selectedUrl;
  } else {
    adSlot.src = selectedUrl;
  }
}

injectAd();

creative-rotation-worklet.js

class SelectURLOperation {
  async run(urls, data) {
    // Initially set the storage to sequential mode for the demo
    await SelectURLOperation.seedStorage();

    // Read the rotation mode from Shared Storage
    const rotationMode = await sharedStorage.get('creative-rotation-mode');

    // Generate a random number to be used for rotation
    const randomNumber = Math.random();

    let index;

    switch (rotationMode) {
      /**
       * Sequential rotation
       * - Rotates the creatives in order
       * - Example: A -> B -> C -> A ...
       */
      case 'sequential':
        const currentIndex = await sharedStorage.get('creative-rotation-index');
        index = parseInt(currentIndex, 10);
        const nextIndex = (index + 1) % urls.length;

        console.log(`index = ${index} / next index = ${nextIndex}`);

        await sharedStorage.set('creative-rotation-index', nextIndex.toString());
        break;

      /**
       * Evenly-distributed rotation
       * - Rotates the creatives with equal probability
       * - Example: A=33% / B=33% / C=33%
       */
      case 'even-distribution':
        index = Math.floor(randomNumber * urls.length);
        break;

      /**
       * Weighted rotation
       * - Rotates the creatives with weighted probability
       * - Example: A=70% / B=20% / C=10%
       */
      case 'weighted-distribution':
        console.log('data = ', JSON.stringify(data));
        // Find the first URL where the cumnulative sum of the weights
        // exceed the random number. The array is sorted by the weight
        // in descending order.
        let weightSum = 0;
        const { url } = data
          .sort((a, b) => b.weight - a.weight)
          .find(({ weight }) => {
            weightSum += weight;
            return weightSum > randomNumber;
          });

        index = urls.indexOf(url);
        break;

      default:
        index = 0;
    }

    console.log(JSON.stringify({ index, randomNumber, rotationMode }));
    return index;
  }

  // Set the mode to sequential and set the starting index to 0.
  static async seedStorage() {
    await sharedStorage.set('creative-rotation-mode', 'sequential', {
      ignoreIfPresent: true,
    });

    await sharedStorage.set('creative-rotation-index', 0, {
      ignoreIfPresent: true,
    });
  }
}

class SetRotationModeOperation {
  async run({ rotationMode }) {
    await sharedStorage.set('creative-rotation-mode', rotationMode);
  }
}

// Register the operation as 'creative-rotation'
register('creative-rotation', SelectURLOperation);
register('set-rotation-mode', SetRotationModeOperation);

Tutorial com capturas de tela

1. Para acessar a rotação de criativos usando a API Select URL e o armazenamento compartilhado, acesse https://shared-storage-demo.web.app/. Escolha a demonstração "Rotação de criativos".

2. Escolha analisar a demonstração como "Editor A". Você será redirecionado para https://shared-storage-demo-publisher-a.web.app/creative-rotation. A página carrega o conteúdo numerado com base nos dados de rotação de criativos salvos no Armazenamento compartilhado, acessados pela API Select URL. Os modos de demonstração para rotação de criativos são sequencial, distribuição uniforme e ponderada. O worklet executa a lógica para selecionar o conteúdo que aparece no iframe. A imagem a seguir mostra a página do editor.

   
   

3. Para conferir o que está armazenado na Shared Storage, navegue até "Application" -> "Shared Storage" nas Ferramentas do desenvolvedor do Chrome. Duas entradas são criadas para o armazenamento compartilhado. Um armazenamento vazio está disponível para a origem https://shared-storage-demo-publisher-a.web.app. Ele vai conter o armazenamento específico para essa origem e vai permanecer vazio para nossa demonstração, já que o editor não precisa gravar no armazenamento compartilhado. Um armazenamento semelhante será criado para o Editor B quando você visitar essa página mais tarde para a demonstração.

   
   

4. Outra entrada de armazenamento compartilhado será criada para a origem https://shared-storage-demo-content-producer.web.app. Esse é o armazenamento do iframe de terceiros incorporado na página do editor. Esse armazenamento será usado para compartilhar dados entre os dois editores disponíveis e coordenar a seleção de criativos. Esse armazenamento compartilhado será usado para salvar informações sobre o criativo mostrado e a estratégia de rotação, salvando dois pares de chave-valor. A primeira chave usada na demonstração é creative-rotation-index, cujo valor é o índice de criativo atual no modo sequencial. A segunda chave é creative-rotation-mode, que determina a estratégia de rotação usada.

   
   

5. Atualizar a página no modo sequencial vai resultar na exibição do próximo criativo na sequência 1, 2, 3, 1, …. O valor da chave creative-rotation-index vai mudar de acordo com o índice do criativo mostrado no modo sequencial.

   
   

6. Mudar o modo de rotação do criativo usando os botões de controle atualiza o valor da chave creative-rotation-mode na estratégia correspondente. Ele será usado pelo código do worklet para escolher o próximo criativo a ser mostrado no iframe. O valor salvo para creative-rotation-index não muda para modos de rotação diferentes de sequencial.

   
   

7. Acesse a página "Editor B" em https://shared-storage-demo-publisher-b.web.app/creative-rotation. No modo sequencial, o criativo mostrado precisa ser o próximo da sequência exibida ao acessar o URL do "Editor A". Ao inspecionar o armazenamento compartilhado do produtor de conteúdo, você pode descobrir que "Editor A" e "Editor B" compartilham o mesmo armazenamento e usam as configurações para selecionar o próximo criativo a ser mostrado e a estratégia de rotação a ser usada.

   
   

8. O armazenamento compartilhado de "Editor B" está vazio, assim como o de "Editor A".

   
   

   Casos de uso

   Todos os casos de uso disponíveis para a API Select URL podem ser encontrados nesta seção. Vamos continuar adicionando exemplos à medida que recebermos feedback e descobrirmos novos casos de teste.

   • Rotecionar criativos de anúncios: armazene dados, como o ID do criativo e a interação do usuário, para determinar quais criativos os usuários veem em diferentes sites.
   • Selecionar criativos de anúncio por frequência: use os dados de contagem de visualizações para determinar quais criativos os usuários veem em diferentes sites.
   • Executar testes A/B: é possível atribuir um usuário a um grupo de experimentos e armazenar esse grupo na Shared Storage para acesso em vários sites.
   • Personalizar a experiência para clientes conhecidos: compartilhe conteúdo e calls-to-action personalizados com base no status de registro ou em outros estados do usuário.

Engajamento e compartilhamento de feedback

A proposta da API Select URL está em discussão ativa e em desenvolvimento e está sujeita a mudanças.

Queremos saber sua opinião sobre a API Select URL.

• Proposta: analise a proposta detalhada.
• Discussão: participe da discussão em andamento para fazer perguntas e compartilhar seus insights.

Fique por dentro

• Lista de e-mails: inscreva-se na nossa lista de e-mails para receber as atualizações e os avisos mais recentes relacionados às APIs Select URL e Shared Storage.

Precisa de ajuda?

• Suporte para desenvolvedores: entre em contato com outros desenvolvedores e receba respostas para suas perguntas no repositório de suporte para desenvolvedores do Sandbox de privacidade.